MilkShape to DTS Exporter Plug-in

Compiled on March 9, 2004
By David Wyand
TheHeadGnome@gnometech.com
www.gnometech.com

Installation
Place the ms2dtsExporter.dll file in the same directory as the MilkShape
executable.

See the bottom of this file for the most recent changes to the exporter.

Original Instructions Included with the Torque Engine:
==============================================================================

This is the exporter DLL for the MilkShape 3D modeler available
from chUmbaLum sOft : //www.swissquake.ch/chumbalum-soft/

The original version of this code was written be Jos Luis Cebrin who
has graciously allowed us to integrate his code into the Torque SDK.
Jos did an awesome job of putting this tool together and the GG staff
is very gratefull for the work he's put in to it.

If you look through the code, you'll notice a little complexity in the
DTS file format. A little background is in order... the dts format was
originally designed to reduce load time processing. This means that the
DTS format is almost a direct representation of how the TS engine stores
data in memory.   This does reduce load times, but also ties the file
format to the run-time implementation, which is not really a good idea.
Changes in run-time implementation, and the pre-processing needed for
the run-time data, resulted in un-planned changes and re-structuring of
the DTS file format. These changes leave us with a file format which
leaves much to be desired.

To help reduce the complications involved in writing new exporters,
the MilkShape exporter is divided into a base DTS "SDK", which provides
the core support needed to deal with DTS files, and a small set of
MilkShape specific files which do the actual conversion.  The long term
goal is split this DTS SDK into a seperate library to be shared between
exporter projects.


Current Functionality
---------------------

The exporter is currently in it's 1.0 "beta" phase. Which means it's
usable. Though there is much functinality to add, and several outstanding
issues.  Maybe "alpha" might be more appropriate :)

- The exporter only exports diffuse texture materials.
- Multi-sequence animations
- Animation only supports bone animation (no texture, texture coor,
  vertex morphing or mesh visibility)
- Support for single collision mesh
- Named nodes.


Exporter Flags & Animation Sequences
------------------------------------

Since MilkShape does not directly support a number of Torque engine features
so the tool has been extended through the use of "hacks".  These are described
more fully below but essentially fall into two categories: mesh flags embeded
in the mesh's name, and specially named materials which are used to declare
animation sequences and exporter options.


Multi-Sequence Animations
-------------------------

Material with special names can be used to declare sequence information.
These materials are ignored during export and are solely used to declare
animation sequences.  Sequence materials are named as follows:

	seq: option, option, ...

All other properties of the material are ignored.  The following options are recognized:

        name=start-end This declares the name of the sequence followed by
                       the starting and ending key frames.  This option must
                       exist for the sequence declaration to be valid. 
        fps=n          The number of frames/second. This value affects the
                       duration and playback speed of the sequence.
        cyclic         Sequences are non-cyclic by default. Cyclic animations
                       automatically loop back to the start and never end.

Examples of valid sequence declarations:
 
        "seq: fire=1-4"
        "seq: rotate=5-8, cyclic, fps=2"
	"seq: reload=9-12, fps=5"


Setting Export Options
----------------------

Materials with special names can be used to set several export options.
These materials are ignored during export and are solely used to set otoins.  Option materials are named as follows:

	opt: option, option, ...

All other properties of the material are ignored.  The following options are recognized:

	scale=n         Shape scale factor, where n is a floating point value.
                        The default scale value is 0.1
        size=n          The minimum visible pixel size, default is 0
        fps=n           The default frames/second value for animations. Each
                        animation sequence may set this value, but if it's
                        not defined by the sequence, this default value is used.
        cyclic          The default animation looping flag.  Each animation
                        sequence may set this value, but if it's not defined
                        by the sequence, this default value is used.

There may be more than one option material.  If the same options are set on mulitple materials, then the last one in the material list is the value used.
Examples of valid material names:

        "opt: fps=10, cyclic"
        "opt: scale=1"


Mesh Option Flags
-----------------

Mesh may have additional flags embedded in the mesh (or group) name. The mesh name follows the following format:

        name: flag, flag, ...

where the : and flags are optional.  The following flags are recognized:

        Billboard       The mesh always faces the viewer
        BillboardZ      The mesh faces the viewer but is only rotated around
                        the mesh's Z axis.
        ENormals        Encodes vertex normals. This flag is deprecated and
                        should not be used, unless you know what your doing.

Examples of legal mesh/group names:
        "box"                   Just called box
        "leaf: Billboard"       Leaf that always faces the viewer
        "leaf: BillboardZ"	Z axis rotated facing leaf

Meshes by defualt do not have any of these flags set.


Issues & Future Developement
----------------------------

- Split off the DTS SDK into it's own library and continue to refine
  it's functionality and API.

- Triangle strips. This is probably the biggest outstanding issue.
  Every mesh triangle is emitted as it's own triangle strip. This is
  very bad :( Triangles need to be stripped by material.  Support
  should be added to the DTSMesh class. 

- Detail support.  Need to add support for progressive meshes. The
  DTSMesh class should automatically produce decimated sub-details
  based off the original art.

- DSQ exporting.  DSQ files are essentially animation sequence files.
  They only contain animation sequence information and can be loaded into
  a shape at run-time.  The same DSQ can be loaded into multiple shapes
  allowing animations to be shared.

- Multiple collision meshes.  The exporter currently selects the first
  mesh named "collision" as a collision mesh.  The torque engine actually
  allows multiple collision meshes per shape and the exporter should
  export all meshes named "collision" as collision meshes.

- Billboard meshes are mesh which the Torque engine automatically
  rotates at run time to face the camera.  There needs to be some way
  of marking meshes.  This could be as simple as naming them "billboard".

- Alpha BSP (or ordered) meshes.  Alpha textured triangles need to be
  rendered in back to front order at run-time for them to render correctly.
  The dts file can contain BSP tree meshes used for this purpose.

- Better material support. There are number of material features (besides
  animation) which MS doesn't support, these include multiple UV mapping
  options, environment mapping flags, addative vs. blended alpha, etc.


Additional Instructions from the CVS Change List:
==============================================================================


Change #: 3922 
Committed by: Tim Gift 
Date: 2004/01/27 23:33:48 

Description:
Integrated a patch from Sven Knie which adds LOS mesh support to the milkshape exporter. Any mesh who's name starts with "LOSCollision" will now be exported as an los mesh. Normal collision meshes now only need to start with the word "Collision". [fyi, I made some changes to the original patch, and not everything has been fully tested...]


Change #: 3911 
Committed by: Tim Gift 
Date: 2003/12/15 21:04:43 

Description:
Integrated a MS exporter patch from Sven (from 3D-Diggers) which fixes a bug with multiple collision meshes being exported.


Change #: 3135 
Committed by: Tim Gift 
Date: 2003/01/22 20:43:49 

Description:
Milkshape Exporter v1.3 Added support for multiple collision meshes in a shape. The collision mesh selection drop down in the export dialog is gone, and now all meshes that start with "Collision" are exported as collision meshes. Also moved DTSPlugin.h from lib/dts to the milkshape dir where it belonged.


Change #: 2889 
Committed by: Tim Gift 
Date: 2002/05/31 15:52:01 

Description:
Merged a patch from Paul Dana which adds animation frame interpolation to the MilkShape DTS exporter. The exporter was previously duplicating frames (instead of interpolating) which resulted in jerky animations.


Change #: 2845 
Committed by: Tim Gift 
Date: 2002/05/02 17:15:22 

Description:
Integrated MilkShape patch submitted by Simon Windmill. This patch includes a small improvement to the MS3D exporter to expose more options in the materials:

Environment mapping can be controlled for the model by use of the shininess
slider (it's the one on the left). Setting the slider to any value but 0 will enable environment mapping for the texture. Note that the texture you are using must have an alpha channel, which will be used to control the per-pixel shininess of the texture. The actual value of the slider is ignored.

Translucency is enabled by setting the MS transparency slider. Setting the slider to any value other than 1.0 (far right) will enable translucency for the texture. Note that the texture you are using must have an alpha channel, which will be used to control the per-pixel translucency of the texture. The actual value of the slider is ignored.

Torque material flags can be set by adding special tags to the MS material
name in the format "Name: option1 [, option2, option3]

Add - Enable additive transparency
Sub - Enable subtractive transparency
Illum - Enable self-illumination (lighting doesn't affect it)
NoMip - Disable mip-mapping
MipZero - Set "MipMapZeroBorder" flag

So for example, a self-illuminating, additive material could be
called "Flare: Add, Illum"

Be aware that MS3D only allows a maximum of 32 characters for a material
name, so try to keep them short if you are using multiple tags.

